Understanding Action Variables

Actions are a powerful and flexible way to transfer information outside of Spend. The following example is an e-mail that would be triggered by the user when a budget item is ready for approval from an outside department, typically finance.

This example uses variables from 3 different parts of Spend:

  • User Details:

    • The user who triggered the action is accessed through
      ${ user.firstName } and ${ user.lastName }

  • Investment Plan Details :

    • The investment plan (budget) name is accessed through ${ budget.name }

    • Additionally, the Uptempo ID (budget ID) is used to create a link back to the item in Uptempo with ${ budget.id }

  • Item Details

    • Items are line items, placeholders, categories and sub-categories. The details of those items (aka. item details) make up most of the variables used within an action, for example ${ item.fyPlan } . Above, several different item variables are used in creating the e-mail.

The example above makes use of variable formatting for the Payment Due By field. In Spend this field is a date but the action needs to know the right way to format it for the e-mail.

To format the date, it is passes through 2 filters. Filters process from left to right, with the result of each filter used by the next one.

In this case, the first filter ? date tells the action to only include the day details in the output and exclude the time.

The second filter ? string.full tells the action to format the date using a predefined 'full' format. In this case, the date would appear like "Friday, October 24, 2014" See the formatting section of the document for more details and other advanced formatting options.

The variables for an action are grouped into sections to make finding them easier as well as to indicate how they should be accessed from within an action template.

Contains variables describing the budget that the action is being executed for, including the name and currency.

Access these variables using the budget prefix. For example:

${ budget. name }

Contains variables for the custom terminology of the budget the action is being executed for. This can be helpful if you have action templates that you may copy between budget hierarchies that have different terminology.

Access these variables using the budget.terms prefix. For example:

${ budget.terms.lineItem }

Contains variables from both the Roll-up panel and the Budget panel for the Budget that the action is being executed for.

Access these variables using the budget prefix. For example:

${ budget.q1FinanceTarget }

Contains general variables about the item the action is being executed for.

Access these variables using the item prefix. For example:

${ item.name }

Contains variables from the Details panel of the item the action is being executed for.

Access these variables using the item prefix. For example:

${ item.objective }

Contains variables from the Grid for the item the action is being executed for. The variable does not have to be visible on the users current view to be accessible, it only needs to be a grid column.

Accessing these variables using the item prefix. For example:

${ item.janPlan }

Totals at the budget level for variables in this category can be accessed using the budget prefix. For example:

${ budget. janPlan }

Contains variables from the Actuals panel for the item the action is being executed for.

Access to those variables requires a loop to access each of the actuals for the item. For example:

<#list item.actuals as actual>
	${ actual.amount }
	${ actual. accountCode }
</#list>

Contains variables from the PO grid for the item the action is being executed for.

Access to those variables requires a loop to access each of the POs for the item. For example:

<#list item.pos as po>	
	${ po.poNumber }	
	${ po.poAmount }
</#list>

Contains variables from the user that is executing the action.

Access these variables using the user prefix. For example:

${ user.firstName }

Contains variables that are unrelated to any other categories.

Access these variables directly. For example:

${ now }

When accessing variables, the system will automatically format the variable for readable output. This means that, especially for numbers, the value may have extra characters that downstream systems can't handle.

For example ${ item.janPlan } might output $1,203,454.23. If the system you want to send the data to cannot handle the commas and the dollar sign, you can use raw variable values.

To use raw variable values, simply append Raw to the variable name. Following the previous example, ${ item.janPlanRaw } will output 1203454.23.

For variables that can contain multiple choices (usually on the Details panel), the individual choices can be accessed either formatted or directly.

For example, this snippet will output all of the choices as a comma separated list:

${ item.multiChoiceVariable }

To access the same variable choices directly, the following structure can be used to output each choice:

<#list item.multiChoiceVariableRaw as multiselect>
${ multiselect.choice } ${ multiselect.percentage }
</#list>

In addition to the values for each variable, you can also access details about the variable itself.

The following information is available about each variable:

  • columnId: The ID for the related column that this data comes from. This is available for Investment grid, Details panel, actuals and PO variables.

  • name: The display name for the variable.

  • fromDate: If the variable has a related column, this is the fromDate for that column as defined in column settings.

  • toDate: If the variable has a related column, this is the toDate for that column as defined in column settings.

Access these variables through the variables prefix. For example:

${ variables.janPlan.name }

To output a section of a template based on the existence of a variable value, you can use the if statement. For example, the following section will be output only if someVariable has a value:

<#if (item.someVariable ?? )>
... Only shown if "someVariable" has a value
</#if>

Many more formatting options are available by using the extensive library provided by the FreeMarker template engine. The FreeMarker manual is available at freemarker.org.

If you would like more information on action variables and FreeMarker formatting please read the following article: FreeMarker Template at a Glance.